<?php

/**
 * \file
 * Classe `Collection`.
 */

/**
 * Collections de paramètres.
 */ 
namespace pilar\ParamCollections /* \cond */ ; /* \endcond */
{

/**
 * Collection de paramètres.
 *
 * \since 16/07/2008
 * \author Matthieu Oviedo <matthieu.oviedo@gmail.com>
 */
class Collection {

const ERR_EXISTING_PARAM = 1;
const ERR_UNDEFINED_PARAM = 2;
 
/**
 * Dictionnaire qui à un nom de paramètre associe sa valeur.
 *
 * \todo
 * Voir de le rendre ce paramètre privé.
 */
public $_params = array();


/**
 * Définit de nouveaux paramètres.
 *
 * \param $params Dictionnaire des paramètres à définir. A chaque
 *                paramètre est associée sa valeur initiale
 *                (elle peut être \c NULL).
 */
public function define($params) {
 if (PILAR_CAREFUL) {
  foreach ($params as $n => $v) {
   if ($this->exists($n)) {
    throw new \Exception(
     'Le paramètre `{$n}` existe déjà.',
     self::ERR_EXISTING_PARAM
    );
   } else $this->_params[$n] = $v;
  }
 } else {
  $this->_params = array_merge($this->_params, $params);
 }
}


/**
 * Réinitialise la collection en effaçant tous les paramètres.
 *
 * \since 12/09/2008
 */
public function clear() {
 unset($this->_params);
 $this->_params = array();
}


/**
 * Change les valeurs d'un ensemble de paramètres existants.
 *
 * \param $params Dictionnaire des paramètres à modifier.
 */
public function set($params) {
 if (PILAR_CAREFUL) {
  foreach ($params as $n => $v) {
   if (!$this->exists($n)) {
    throw new \Exception(
     "Le paramètre `{$n}` n'est pas défini.",
     self::ERR_UNDEFINED_PARAM
    );
   } else $this->_params[$n] = $v;
  }
 } else {
  $this->_params = array_merge($this->_params, $params);
 }
}


/**
 * Modifie la valeur d'un paramètre existant.
 * 
 * \param $name Nom du paramètre.
 * \param $value Valeur à attribuer au paramètre.
 *
 * \since 22/09/2008
 */
public function __set($name, $value) {
 if (PILAR_CAREFUL && !$this->exists($name)) {
  throw new \Exception(
   "Le paramètre `{$name}` n'existe pas.",
   self::ERR_UNDEFINED_PARAM
  );
 } else $this->_params[$name] = $value;
}


/**
 * Retourne la valeur d'un paramètre.
 *
 * \param $name Nom du paramètre.
 * \return Valeur du paramètre.
 */
public function get($name) {
 if (PILAR_CAREFUL && !$this->exists($name)) {
  throw new \Exception(
   "Le paramètre `{$name}` n'existe pas.",
   self::ERR_UNDEFINED_PARAM
  );
 } else return $this->_params[$name];
}


/**
 * Retourne la valeur d'un paramètre.
 *
 * \param $name Nom du paramètre.
 * \return Valeur du paramètre.
 */
public function __get($name) {
 return $this->get($name);
}


/**
 * Détermine si un paramètre existe dans la collection.
 *
 * C'est le cas si il a été défini via la méthode \a define .
 *
 * \param $name Nom du paramètre.
 * \return \c TRUE si le paramètre existe, \c FALSE sinon.
 *
 * \since 14/02/2009
 */
public function exists($name) {
 return array_key_exists($name, $this->_params);
}

} // Class.

} // Namespace.

?>
